home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format 16 / af016.adf / Lib counter readme < prev    next >
Text File  |  1978-01-04  |  14KB  |  302 lines
  1. ------------------------------------------------------------------------
  2. Lib-Counter version 1.0
  3. (c) Copyright Alan J. Edmonds  May, June 1990
  4. ------------------------------------------------------------------------
  5. DISCLAIMER
  6. Every effort has been made to produce a reliable, high quality program.
  7. However I can neither guarantee nor be held legally responsible for any
  8. errors in the program or for any loss or damage caused by the use of the
  9. Program.
  10.  
  11. Alan J. Edmonds.
  12. ------------------------------------------------------------------------
  13. 1)   Introduction
  14. ------------------------------------------------------------------------
  15. Lib-Counter will count and display (in real time!) the number of calls made
  16. to any of the Amiga library routines which you care to select.  There are
  17. basically two ways to look at Lib-Counter:-
  18.  
  19. 1)  As a U.H.  (Useless Hack!)
  20. 2)  As a U.T.  (Useful Tool)
  21.  
  22. I'll let you make you're own mind up!
  23.  
  24. If you look at the right library routines,  Lib-Counter will give you an idea
  25. of what the Amiga spends its time doing.  And if you're a programmer, you
  26. might (that's a big MIGHT...) find Lib-Counter helpful with the testing of
  27. your programs.  It can also tell you which library routines are used most
  28. often by other programmers!
  29.  
  30. ------------------------------------------------------------------------
  31. 2)   How to start the program
  32. ------------------------------------------------------------------------
  33. Lib-Counter may be run directly from either CLI or Workbench.
  34. From Workbench, just double click the Lib-Counter icon, and away you go!
  35. From the CLI (with the program in your current directory) you can just enter:
  36. Lib-Counter {RETURN}
  37. Or to run it in the background and keep the CLI available for other uses:
  38. RUN Lib-Counter {RETURN}
  39.  
  40. ------------------------------------------------------------------------
  41. 3)   Using the program
  42. ------------------------------------------------------------------------
  43.  
  44. The entire program is controlled by selecting various gadgets with the
  45. mouse (surely every Amiga user must know how to do that!)
  46. When run, a copyright message is displayed - press either of the OK buttons
  47. to continue.  The main window is then displayed with the following options:-
  48.  
  49. 'Add A Counter...'
  50. ------------------
  51. This gadget will bring up a display similar to a file requester, showing a
  52. list of library names to select.  You can scroll through the list by
  53. clicking the large up and down arrows.  To select a library, just point and
  54. click on its name.  If you decide not to add a counter, click cancel.
  55.  
  56. Once a library has been selected, you will be presented with a list of
  57. routine names for that particular library, which may be scrolled with the
  58. arrows.
  59. Choose the required routine by clicking on it.
  60. If you want to select a different library instead, clicking LIBS will take
  61. you back to the library name list.  Cancel takes you back to the main screen.
  62.  
  63. As soon as a routine is chosen, a counter will be initialised and displayed,
  64. unless a problem occurrs - in which case an appropriate error message will
  65. be displayed.
  66.  
  67. 'Remove A Counter...'
  68. ---------------------
  69.  
  70. This option is identical to Add A Counter except that when you select a
  71. routine, (you've guessed it!) the counter will be removed.  If the selected
  72. routine didn't have a counter, an error message will appear.
  73.  
  74. 'Remove All Counters'
  75. ---------------------
  76.  
  77. This will save you the trouble of doing many Remove A Counter operations, by
  78. removing them all in one go.  If no counters are running, then nothing will
  79. happen!
  80.  
  81. Note that there may be some disk access, because the program will open and
  82. scan all the disk based libraries for counters, as well as the built in
  83. ones.  So if you only have one disk drive,  a system requester may appear,  
  84. asking for you to insert the Workbench disk.
  85.  
  86. 'Tidy Screens'
  87. --------------
  88.  
  89. If you start up several counters, you'll find this option very useful.  It
  90. will arrange all the counter screens in a neat stack at the bottom of the
  91. display.
  92. It will also bring any counter screens hidden behind the Workbench screen to
  93. the front.
  94. The Workbench screen is also moved to the top of the display (if it wasn't
  95. there already)
  96. If no counters are present then nothing will happen!
  97.  
  98. Note that only the first 10 counter screens that Tidy Screens finds are
  99. moved.  If you want more than 10 at a time, then you'll have to position
  100. them manually!
  101.  
  102. 'About'
  103. -------
  104.  
  105. Brings up a requester containing some details about the program!
  106. Press one of the OK gadgets to continue.
  107.  
  108. 'Quit'
  109. ------
  110.  
  111. Terminates the program.  Note that you may quit and leave counters running -
  112. this will save about 35k of memory.  You may then re-run the program at any
  113. time and (say) do a Remove All Counters or whatever.
  114.  
  115.  
  116. Note about the requesters
  117. -------------------------
  118.  
  119. If you select About or one of the errors listed below occurrs, then the
  120. Workbench screen gets moved to the front of all the other screens -
  121. including any counter screens you've got running.  Therefore, I have
  122. provided two 'OK' gadgets in my 'Error', 'Copyright' and 'About' requesters
  123. as follows:-
  124. 'OK' - this just removes the requester and leaves Workbench at the front.
  125. 'OK + Workbench to back' - pushes Workbench to the back of the display and
  126. removes the requester.
  127. This saves you from having to manipulate the screen to back / front gadgets.
  128.  
  129. ------------------------------------------------------------------------
  130. 4)   Error messages
  131. ------------------------------------------------------------------------
  132.  
  133. Can't open that library
  134. -----------------------
  135. The selected library could not be found. You may have selected a library
  136. which is disk based and not in your current LIBS: directory.
  137. Some of the libraries in the list will not open.  I entered them as shown in
  138. the 'Amiga ROM Kernel Reference Manual' and the 'Amiga System Programmers
  139. Guide' - but they just won't open! (As far as I know these libraries were
  140. used in earlier versions of the system and are now obsolete.)
  141. The libraries in question are as follows:-
  142.  
  143. clist,  console,  potgo,  and timer.
  144. (As I went to the trouble of entering all the data for these libraries, I
  145. decided to leave them in.)
  146.  
  147. That routine already has a counter
  148. ----------------------------------
  149. Only one counter per routine is allowed.  If you can't seem to find the
  150. counter for that routine,  its screen may be behind the Workbench screen. 
  151. You might like to press 'Tidy Screens' to bring the counters to the front.
  152.  
  153. Couldn't find a counter there
  154. -----------------------------
  155. You asked for a counter to be removed where there isn't one.
  156.  
  157. Out of memory
  158. -------------
  159. You're really pushing things if you get this one!  Close some windows,  quit
  160. one of the programs you're running or remove some counters, then try again.
  161.  
  162. (Another way around the 'Out Of Memory' error which I once read about was to
  163. 'Buy more memory'! - But I'm not going to put that one in.)
  164.  
  165. Unknown vector type
  166. -------------------
  167. Something is seriously wrong if you get this error.  Another program you are
  168. using may have corrupted a library vector.  It may be the result of a virus.
  169.  
  170. ----------------------------------------------------------------------
  171. 5)   Routines to try counters with
  172. ----------------------------------------------------------------------
  173. Here is a list of some of the more interesting ones (Are there any ?):-
  174.  
  175. Graphics routines OwnBlitter and DisOwnBlitter - A surprisingly large number
  176. of programs / tasks want to own the blitter!  Try moving a window or typing
  177. & pressing return a few times in a CLI.
  178. Graphics Draw (draws straight lines) - see how fast the counter goes as you
  179. size or move windows!
  180. Graphics Text - every character you type in a CLI calls Text.
  181. Graphics MoveSprite - every time you move the mouse pointer, guess what will
  182. happen to this counter...!
  183. If FastFonts is switched on,  each time text is printed (say by typing in a
  184. CLI),  the Graphics routines BltTemplate and BltPattern are called.
  185. If FastFonts is off, BltClear is called in addition to these two.
  186.  
  187. Exec AllocMem and FreeMem - (allocate and free memory) get a lot of calling
  188. - especially when you move a window in a crowded screen.  
  189.  
  190. Exec Switch - This tends to give an indication of how busy the processor is,
  191. by incrementing at a different rate for varying situations.
  192. Exec OpenLibrary and Forbid - On my machine these two tick over at one count
  193. per second!  (May be useful as a stopwatch ?!!!)
  194. Exec FindTask - Every second, 3 tasks get 'looked for'!
  195.  
  196. Some libraries seem to get little or no use by the operating system via the
  197. standard 'jump table' calling method.  For example, if you put a counter on
  198. Intuition MoveWindow and try moving a window - nothing!  So, either
  199. intuition does it internally, or perhaps the work gets done by other
  200. Libraries - in this case the Layers library MoveLayer function.
  201. The fact that counters added to Intuition (and Dos, to name another) are
  202. relatively dead may be put to good use, because it means that any calls that
  203. ARE made to their routines will probably be from an Applications program. 
  204. This makes it much easier to see what a program is doing, because any other
  205. (systems) calls will not be shown on the counter.
  206.  
  207. ----------------------------------------------------------------------
  208. 6)   'Technical notes'  (99% of people may want to skip this section)
  209. ----------------------------------------------------------------------
  210. The program should run on any Amiga.  It was developed on a 1MB Amiga 500. 
  211. I also tested it with the RAM expansion switched off.  It will return all
  212. memory and close all Libraries opened after all the counters are removed.
  213.  
  214. Lib-Counter ignores the current 60/80 character size value in preferences,
  215. so that if you're set to 60, the text will not go off the end of the window.
  216.  It's surprising how many other programs produce corrupted displays when the
  217. 60 column text size is in use!  (Sorry to TV only users)
  218.  
  219. Even though Lib-Counter is 100% Assembly Language,  the speed at which the
  220. display updates in the library requesters may seem a little slow to some
  221. people. The reason for this is that the intuition function RefreshGadgets is
  222. SLOW (especially with > 10 gadgets to refresh) and I make 3 calls to it each
  223. time an arrow is clicked.  I may change this in a future version.
  224.  
  225. A possible problem area is to use Lib-Counter with another program which
  226. modifies the Library Vectors.  An example of such a program is FastFonts. 
  227. Not all will cause trouble; indeed FastFonts is good in this respect - if
  228. you add a counter to Graphics/Text with FF off, and then run FF, it will
  229. warn you about the modified vector and quit.  Other programs may not be so
  230. carefull and this is something to bear in mind.  In other words, don't risk
  231. using Lib-Counter just before you save something you've been working on for
  232. 4 hours!!!  Save your work, then play with it!
  233. Having said that,  it hasn't crashed on me yet.
  234.  
  235. The program itself takes about 35k of system memory (some chip, some fast -
  236. if available).  Each counter added consumes less than 3k - even though a new
  237. screen is opened for each counter.  The reason for this is that the screen
  238. height is set only a little taller than the title bar.
  239. After much thought, I decided on using screens rather than (say) a large
  240. window, in order to make each counter stand-alone.  With this method,  room
  241. can usually be found for up to 5 counters at the bottom of the Workbench
  242. screen without too much trouble - and this is where the 'Tidy Screens'
  243. option places the screens.  I decided against making this option operate
  244. automatically after each 'Add A Counter', so that the user may position the
  245. screens differently and then add further counters without repeated
  246. re-positioning.
  247.  
  248. When developing Lib-Counter I found the structure of the DOS library to be
  249. different to the other libraries in the way that the jump table is composed.
  250. (Perhaps everybody else knows this already - but I'll mention it anyway!)
  251. The other libraries consist of the following type of jump table:-
  252.  
  253. JMP FCxxxx
  254. JMP FCnnnn
  255. etc
  256.  
  257. Whereas the DOS library goes:-
  258. MOVEQ #0,D0
  259. BRA xxxx
  260. MOVEQ #0,D0
  261. BRA nnnn
  262.  
  263. This caused a few headaches when it came to Adding a counter to a DOS
  264. routine, because my program assumed that all the libraries contained JMP
  265. instructions. It took what it thought to be the system routine address (to
  266. go to after incrementing the counter) from the last 4 bytes of the library
  267. vector - but in the case of DOS this was a BRA instruction!  Therefore, any
  268. call to the selected DOS routine caused a spectacular crash!  After I
  269. discovered this,  I changed the program to test the vector type before
  270. deciding what to do - and it now works with all the current (and hopefully
  271. future) Library Vector types.
  272.  
  273. I would also like to mention another small problem I had in the development
  274. stages.  At first, I used the Graphics routines Move and Text to print the
  275. counter value every time it changed.  However, if a counter was added to
  276. Text, Move or any routine called by Text or Move (e.g. OwnBlitter) then a
  277. continuous loop was formed.  To solve this problem, the program writes its
  278. own font data directly to the screen bitmap.
  279.  
  280. ----------------------------------------------------------------------
  281. My address:-
  282. ----------------------------------------------------------------------
  283. If anybody wants to contact me (for example to send me their unwanted gifts
  284. such as an A3000, Hard Disk Drive, Laser Printer ... should I go on ?) then
  285. please write to :-
  286.  
  287. Alan J. Edmonds
  288. 5 Beatrice Street
  289. Latchford
  290. Warrington
  291. Cheshire
  292. WA4 1DR
  293.  
  294. {England}
  295.  
  296. I would also be interested in bug reports, comments (reasonably friendly
  297. ones, please) etc.
  298.  
  299. END OF FILE
  300.  
  301.  
  302.